These externals are © 89, Antoine Latour. They are free, and your are allowed to distribute them in public domain products, if the line : "Externals ModDialog, DisDialog, HandleDialog, SetDialog, DialogValue & ParamDialog are © 89, Antoine Latour" appears clearly in your stacks. For any commercial products, please contact me at the following adress :
Antoine Latour, 11, rue du Mai 1945, 91150 Etampes, France.
In order to use dialogs in Hypercard stacks, i've implemented larges parts of the dialog manager in these six externals :
ΓÇó ModDialog, which bring up a dialog window on the screen;
ΓÇó DisDialog, which dispose it;
ΓÇó HandleDialog, which return you the item choosen by the user;
ΓÇó DialogValue, which return the value or the state of an item of the dialog item list;
ΓÇó SetDialog, which allow you to change the state or the value of an item of the dialog item list;
ΓÇó ParamDialog, which allow you to change the text displayed by a dialog.
To use these commands, you need a good knowledge of the dialog manager of the Macintosh. See Inside Macintosh Vol I and III.
The first thing you've to do is to design your dialog. You can use ResEdit, Rmaker or other software to create them. If you use ResEdit, create a new file, then create a new DLOG resource. Warning : the visible attribute may be set to true, RefCon may be set to 0. All other attributes, in particular GoAwayFlag, may be set to false.
Once your dialog is designed, with it's item list, you've to note carrefully : the ID number of the DLOG, and the item number of all of the items. Usually, item 1 may be the OK button of the dialog.
Then, you've to past the DLOG, the DITL, and all other associated resources ( PICT, ICON, etc.. ) into your stack.
Remember this : In order to work, all of these commands need a parameter, given you by the ModDialog function. Put this parameter in a global variable, and declare it at any point of your script.
ModDialog < ID >
ΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇôΓÇô
ModDialog is a function which look in your stack, then in your home stack, then in HyperCard himself, at least in the system file, to find the dialog specified in the ID parameter. Then, he brings its on the screen, and return the pointer on it. YOU NEED to collect this pointer into a variable, for all others calls to theses commands.
Example :
on Bring_up_dialog
global MyDialog
put ModDialog (500) into MyDialog
end Bring_up_dialog
In Case of error, the value returned by ModDialog may be :
* 0 if the parameter passed to ModDialog is non-coherent;
* -1, if the resource doesn't exists.
Obviously, in both of these cases, ModDialog doesn't show any dialog on the screen.
HandleDIalog is a function that return the item number choosen by the user. Its a one-event function. In most cases, you must call HandleDialog along a repeat loop, and you will exit this loop when the 'OK' or 'Cancel' button will be choose. HandleDialog return an integer, between 1 and 64 ( the maximum number of items in a DITL ).
Example :
on Test_Dialog
global MyDialog
repeat
put HandleDialog(MyDialog) into UserAnswer
if UserAnswer is 1 then -- OK Button
exit repeat
else if UserAnswer is 2 then -- Cancel button
exit to HyperCard
end if
end repeat
-- here is the script wich look for the value of differents items
-- after that, you have to use DisDIalog to put away the dialog
end Test_Dialog
NOTE : Only enabled items can be seen by ModDialog. See your DITL with resEdit to Enable ou disable your item.
CAUTION : A call to HandleDIalog with a <pointer> parameter which doesn't exist will cause a system error.
Giving a pointer on a dialog, DisDialog release it off the screen, releasing also the memory occupied by the dialog and item list structures.
Example :
On Bring_off_dialog
Global MyDialog
DisDialog MyDialog
end Bring_off_dialog
CAUTION : Only two tests are made : DisDialog check if the <pointer> parameter is 0 or odd. In these cases, DisDialog do nothing. But if you give it a non-zero and even parameter, which doesn't correspont to a dialog pointer, the crash will be awfull !
Giving a pointer on a dialog, and an item number of the item list, DialogValue return the value or the state of this item, depending of what kind of item you're speaking about. If the <item> is a check-box or a radio-button, DialogValue return 1 or 0, depending if the control is highlighed or not. If the item is a button, a staticText, or editableText, dialogValue give you the text of this control. If the item is a userItem or an icon, DialogValue do nothing. If the <item> parameter doesn't correpond to an item existing in the dialog, DisDialog will return '0' as its value.
Example :
On What_Value
global MyDialog
put DialogValue (MyDialog,1) into ValueOfFirstItem
put DialogValue (MyDialog,2) into ValueOfSecondItem
end What_Value
CAUTION : Calling DialogValue with a <pointer> parameter wich doesn't exist may be... special.
Given a pointer on a dialog, and an item number of the item list, SetDialog will set a value or a state to the item, depending of what king of item you're speaking about. If the <Item> is a check-box or a radio-button, SetDialog will set the item to highlighed or not. In this case, you will use 1 or 0 in the third parameter, with 1 to highligh to item. If the <item> is a static-text, editable-text, or a button, SetDialog will set the test of this item to [value], which is a sample string. Only first 255 caracters will be used.
Examples :
On Set_Item
-- set a checkbox ( item 3 of the DITL ) to on
global MyDialog
SetDialog MyDlog,3,1
end Set_Item
on Set_Item
-- set a static-text ( item 3 of the DITL ) to a string
ParamDialog provides a means of substituting text in statText items: Text1 through Text3 will replace the special strings '^0' through '^3' in all statText items in subsequent dialog, notified in the <pointer> parameter. Pass empty strings for parameters not used.
During the repeat ... HandleDialog ... end repeat loop, user may click in check-boxes or radio-button. If there is more of 2 radio-button in a group, you must switch off all radio-buttons first, then highligh the radio-button the user choose. I recommend to use this kind of script :
On Display_Dialog
global MyDialog
-- Display the dialog first
put ModDialog (500) into MyDialog
-- test if the dialog is displayed or not
if MyDialog is 0 then exit to hypercard
if MyDialog is -1 then exit to hypercard
-- In this dlog, there is two distincts group of radio-
-- button, and a group of 2 check-boxes. Only one of
-- radio-button of each group must be highligh. We --
-- create two series of radio-button :
-- item number of the radio-btn of first group :
put "3,4,5" into RadButtons1
-- item numbers of the radio-btn of second group :
put "6,7,8" into RadButtons2
-- item numbers of the two check-boxes :
put "9,10" into CheckBoxes
-- repeat loop
repeat
put HandleDialog(MyDialog) into userClic
if userClic is in RadButtons1 then
-- user clic in first group of radio-buttons
-- first, switch off all these radio-buttons :
repeat with i is 3 to 5
SetDialog MyDialog,i,0
end repeat
-- then we highligh the radio-button choosen
SetDialog MyDialog,UserClic,1
end if
if userClic is in RadButtons2 then
-- user clic in second group of radio-buttons
-- first, switch off all these radio-buttons :
repeat with i is 6 to 8
SetDialog MyDialog,i,0
end repeat
-- then we highligh the radio-button choosen
SetDialog MyDialog,UserClic,1
end if
if userClic is in CheckBoxes
-- user clic in a check-boxe. Is it actually
-- highligh or not ?
if DialogValue(MyDialog,UserClic) is O then
-- not hilight, so we select it
SetDialog MyDialog,UserClic,1
else
-- if it's highlighed, we switch it off
SetDialog MyDialog,UserClic,0
end if
end if
if userClic is 1 then exit repeat -- ok button
end repeat
-- Here is the script wich allow us to see what's button a
-- selected :
repeat with i is 3 to 5
if DialogValue(MyDialog,i) is 1 then
put i into FirstGroupChoice
end if
end repeat
repeat with i is 6 to 8
if DialogValue(MyDialog,i) is 1 then
put i into SecondGroupChoice
end if
end repeat
-- Now, the item number of each radio-button group
-- currently selected are stored in the variables
-- 'firstGroupChoice' and 'SecondGroupChoice'
-- Look for the checkBoxes
if DialogValue(MyDialog,9) is 1 then put true into ¬
FirstBox
if dialogValue(MyDialog,10) is 1 the put true into ¬
SecondBox
-- Now, we dispose the dialog :
DisDialog (MyDialog)
end Display_dialog
See the script of card button 'Let's try' of this stack for more infos.
I apologize for my 'non-fluent' english. But why don't you speak french as everybody does ?
